데이터베이스 쿼리 계약 관리하기

전달하려는 주요 내용

업무 프로젝트에서 대부분의(90%) 업무는 데이터베이스의 CRUD 쿼리를 수행합니다.

• HandStack에서는 이러한 반복적인 데이터베이스 작업을 어떻게 효율적으로 관리할까요?
• 데이터베이스 쿼리를 하나의 계약(Contract)처럼 XML 파일로 관리하는 방법을 알아봅니다.
• 이를 통해 복잡한 서버 코드 없이 빠르고 명확하게 데이터 로직을 구현할 수 있습니다.

쿼리 계약이란?

• SQL 쿼리 자체를 하나의 독립적인 파일(*.xml)로 분리하여 관리하는 방식입니다.

• 개발자는 비즈니스 로직에 집중하고, 데이터 접근은 약속된 *.xml 파일을 통해 처리합니다.

• 장점

  • 코드와 SQL의 분리로 명확한 역할 분담
  • SQL 변경 시 서버 재컴파일 및 재배포 불필요
  • 쉬운 유지보수 및 재사용성 증가
  • MyBatis 처럼 개발자가 직접 SQL 쿼리를 작성하고 관리
  • 복잡하거나 최적화가 필요한 쿼리, 혹은 데이터베이스 특정 기능을 활용

지원 데이터베이스 및 연결 설정

• HandStack은 다양한 데이터베이스를 지원합니다.

  • SQL Server
  • Oracle
  • MySQL & MariaDB
  • PostgreSQL
  • SQLite

• 데이터베이스 연결 정보는 다음 파일에서 관리합니다.

  • %HANDSTACK_SRC%/2.Modules/dbclient/module.json

왜 데이터베이스가 필요한가요?

애플리케이션의 핵심은 데이터입니다.

• RDBMS는 엄격한 스키마를 가지고 있어 데이터의 구조와 타입이 명확하게 정의됩니다. 이는 데이터 품질을 높이고, 애플리케이션 개발 시 데이터 모델에 대한 예측 가능성을 제공합니다.
• 사용자의 정보, 게시글, 상품 목록 등 모든 중요한 데이터를 안정적인 트랜잭션 처리로 저장하고 관리하는 공간이 필요합니다.
• 정규화를 통해 데이터 중복을 최소화하고 데이터 간의 복잡한 관계 JOIN하여 다양한 관점에서 데이터를 조합하고 분석하는 데 매우 강력합니다.

연결 문자열 관리

• HandStack 프로젝트가 이 데이터베이스와 통신하기 위해서는 연결 정보가 필요합니다.
• 이 연결 정보를 '연결 문자열 (Connection String)'이라고 부릅니다.
• 연결 문자열은 데이터베이스의 주소, 계정 정보 등을 담고 있는 특별한 텍스트입니다. 이 문자열을 암호화 해서 관리하거나 키를 수급해서 사용해야합니다.

HandStack 데이터베이스 설정 파일

HandStack은 module.json 파일 하나로 데이터베이스 연결을 관리합니다.

• 개발 소스 위치

  • $(HANDSTACK_SRC)/2.Modules/dbclient/module.json
  • 프로젝트의 원본 소스에 포함된 설정 파일입니다.

• 빌드 후 위치

  • $(HANDSTACK_HOME)/modules/dbclient/module.json
  • 실제 실행 환경에서 사용되는 설정 파일입니다.

module.json 설정 항목 살펴보기

dbclient 모듈의 module.json 파일은 다음과 같은 구조로 되어 있습니다.

{
  "DataSources": [
    {
      "ApplicationID": "Default",
      "ProjectID": "Default",
      "DataSourceID": "Main",
      "DataProvider": "SqlServer",
      "ConnectionString": "서버=localhost;데이터베이스=YourDB;...",
      "IsEncryption": false,
      "Timeout": 30
    }
  ]
}

안전한 연결 문자열 관리 (1/2)

중요한 접속 정보를 코드에 그대로 노출하는 것은 위험합니다.
HandStack CLI는 간단한 명령어로 연결 문자열을 암호화/복호화하는 기능을 제공합니다.

연결 문자열 암호화에 호스트명이 포함되기 때문에 대상 호스트에서 만들어야 합니다.

• 연결 문자열 암호화

  handstack encrypt --format=connectionstring --value="[연결 문자열]"
  

• 암호화된 문자열 복호화

  handstack decrypt --format=connectionstring --value="[암호화된 문자열]"
  

안전한 연결 문자열 관리 (1/2)

암호화된 문자열은 ConnectionString에 넣고 IsEncryption 값을 true로 변경하여 사용합니다.

• DataSourceID: 여러 DB를 사용할 경우, 이를 구분하는 고유 ID입니다.
• DataProvider: 연결할 데이터베이스 종류 (예: SqlServer, Oracle, MariaDB 등)
• ConnectionString: 실제 데이터베이스 연결 정보
• IsEncryption: 연결 문자열 암호화 여부

연결 문자열 복호화에 호스트명을 검증하기 때문에 다른 호스트에서 복호화할 수 없습니다.

핸즈온: 직접 확인해보기

이제 여러분의 프로젝트에서 데이터베이스 설정 파일을 직접 열어봅시다.

1. Visual Studio Code에서 $(HANDSTACK_HOME)/modules/dbclient/module.json 파일을 엽니다.
2. ConnectionString 항목을 찾아 로컬 SQL Server 환경에 맞게 수정합니다.
   • 예시: Server=localhost;Database=handstack_db;User Id=sa;Password=your_password;
3. IsEncryption 값이 false인지 확인합니다.

DataSources는 배열([])로 되어 있어, 여러 개의 데이터베이스 접속 정보를 추가할 수 있습니다. 이를 통해 테넌트별로 다른 데이터베이스를 연결하는 것도 가능합니다.

header 정보 확인하기

<header>
    <application>HDS</application>
    <project>TST</project>
    <transaction>TST010</transaction>
    <datasource>DB01</datasource>
    <use>Y</use>
    <desc>데이터베이스 거래 테스트 예제</desc>
</header>

header 는 삭제 가능하며 이때 디렉토리와 파일명으로 내용이 구성되며 datasource 는 module.json 의 DefaultDataSourceID 항목을 사용

statement 매개변수 데이터 타입

<param id="@UserID" type="String" length="255" value="NULL" />

대부분의 경우 데이터베이스에 상관없이 다음의 데이터 타입을 사용

• String
• Int32, Int64, Int16
• Long, Decimal, Currency, Double, Float
• DateTime, Date, Time

DbType 열거형 참조

statement 매개변수 데이터베이스 데이터 타입

필요한 경우 native="Y" 속성을 선언 하여 다음의 데이터베이스의 고유 데이터 타입을 사용

• SqlDbType: http://msdn.microsoft.com/ko-kr/library/system.data.sqldbtype.aspx
• OracleDbType: https://docs.oracle.com/html/B28089_01/OracleDbTypeEnumerationType.htm#i1017320
• MySqlDbType: https://dev.mysql.com/doc/dev/connector-net/8.0/api/data_api/MySql.Data.MySqlClient.MySqlDbType.html
• NpgsqlDbType: https://www.npgsql.org/doc/api/NpgsqlTypes.NpgsqlDbType.html
• SQLiteDbType: https://docs.microsoft.com/ko-kr/dotnet/standard/data/sqlite/types

요약 정리 및 Q&A

• 쿼리 계약의 개념과 이점
• 다양한 데이터베이스 지원 및 연결 설정
• 안전한 연결 문자열 관리
• 쿼리 계약(XML)의 header 정보
• statement 매개변수 데이터 타입